<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Changes in reference handling</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="migration51.changes.html">Key PHP 5.1.x features</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="migration51.reading.html">Reading []</a></div>
 <div class="up"><a href="migration51.html">Migrating from PHP 5.0.x to PHP 5.1.x</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="migration51.references" class="section">
  <h2 class="title">Changes in reference handling</h2>
  <ul class="itemizedlist">
   <li class="listitem">
    <p class="para">
     <a href="migration51.references.html#migration51.references-overview" class="link">Overview</a>
    </p>
   </li>
   <li class="listitem">
    <p class="para">
     <a href="migration51.references.html#migration51.references-fails" class="link">Code that worked under PHP
      4.3.x, but now fails</a>
    </p>
   </li>
   <li class="listitem">
    <p class="para">
     <a href="migration51.references.html#migration51.references-error" class="link">Code that worked under PHP
      4.3.x, but now throws an error</a>
    </p>
   </li>
   <li class="listitem">
    <p class="para">
     <a href="migration51.references.html#migration51.references-works" class="link">Code that failed under PHP
      4.3.x, but now works</a>
    </p>
   </li>
   <li class="listitem">
    <p class="para">
     <a href="migration51.references.html#migration51.references-didnotwork" class="link">Code that
      should have worked under PHP 5.0.x</a>
    </p>
   </li>
   <li class="listitem">
    <p class="para">
     <a href="migration51.references.html#migration51.references-warnings" class="link">Warnings that came and
      went</a>
    </p>
   </li>
  </ul>

  <div class="section" id="migration51.references-overview">
   <h2 class="title">Overview</h2>
   <p class="para">
    From the PHP script writer&#039;s point of view, the change most likely to
    impact legacy code is in the way that references are handled in all PHP
    versions post-dating the PHP 4.4.0 release.
   </p>
   <p class="para">
    Until and including PHP 4.3, it was possible to send, assign or return
    variables by reference that should really be returned by value, such as
    a constant, a temporary value (e.g. the result of an expression), or the
    result of a function that had itself been returned by value, as here:
   </p>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$foo&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">"123"</span><span style="color: #007700">;<br /><br />function&nbsp;</span><span style="color: #0000BB">return_value</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;global&nbsp;</span><span style="color: #0000BB">$foo</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">$foo</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">$bar&nbsp;</span><span style="color: #007700">=&nbsp;&amp;</span><span style="color: #0000BB">return_value</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
   <p class="para">
    Although this code would usually work as expected under PHP 4.3, in the
    general case the result is undefined. The Zend Engine could not act
    correctly on these values as references. This bug could and did lead to
    various hard-to-reproduce memory corruption problems, particularly
    where the code base was large.
   </p>
   <p class="para">
    In PHP 4.4.0, PHP 5.0.4 and all subsequent PHP releases, the Engine was
    fixed to &#039;know&#039; when the reference operation is being used on a value
    that should not be referenced. The actual value is now used in such
    cases, and a warning is emitted. The warning takes the form of an
    <strong><code>E_NOTICE</code></strong> in PHP 4.4.0 and up, and
    <strong><code>E_STRICT</code></strong> in PHP 5.0.4 and up.
   </p>
   <p class="para">
    Code that could potentially produce memory corruption can no longer do
    so. However, some legacy code might work differently as a result.
   </p>
  </div>

  <div class="section" id="migration51.references-fails">
   <h2 class="title">Code that worked under PHP 4.3, but now fails</h2>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">function&nbsp;</span><span style="color: #0000BB">func</span><span style="color: #007700">(&amp;</span><span style="color: #0000BB">$arraykey</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">$arraykey</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;function&nbsp;returns&nbsp;by&nbsp;value!<br /></span><span style="color: #007700">}<br /><br /></span><span style="color: #0000BB">$array&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'a'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'b'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'c'</span><span style="color: #007700">);<br />foreach&nbsp;(</span><span style="color: #0000BB">array_keys</span><span style="color: #007700">(</span><span style="color: #0000BB">$array</span><span style="color: #007700">)&nbsp;as&nbsp;</span><span style="color: #0000BB">$key</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$y&nbsp;</span><span style="color: #007700">=&nbsp;&amp;</span><span style="color: #0000BB">func</span><span style="color: #007700">(</span><span style="color: #0000BB">$array</span><span style="color: #007700">[</span><span style="color: #0000BB">$key</span><span style="color: #007700">]);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$z</span><span style="color: #007700">[]&nbsp;=&amp;&nbsp;</span><span style="color: #0000BB">$y</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$z</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;<br /></span>&lt;</span>
</code></div>
    </div>

    <p class="para">
     Running the above script under any version of PHP that pre-dates the
     reference fix would produce this output:
    </p>
    <div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
  [0]=&gt;
  &amp;string(1) &quot;a&quot;
  [1]=&gt;
  &amp;string(1) &quot;b&quot;
  [2]=&gt;
  &amp;string(1) &quot;c&quot;
}
</pre></div>
    </div>
    <p class="para">
     Following the reference fix, the same code would result in:
    </p>
    <div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
  [0]=&gt;
  &amp;string(1) &quot;c&quot;
  [1]=&gt;
  &amp;string(1) &quot;c&quot;
  [2]=&gt;
  &amp;string(1) &quot;c&quot;
}
</pre></div>
    </div>
   </div>
   <p class="para">
    This is because, following the changes, <em>func()</em>
    assigns by value. The value of <var class="varname"><var class="varname">$y</var></var> is re-assigned,
    and reference-binding is preserved from <var class="varname"><var class="varname">$z</var></var>. Prior to
    the fix, the value was assigned by reference, leading <var class="varname"><var class="varname">$y</var></var>
    to be re-bound on each assignment. The attempt to bind to a temporary
    value by reference was the cause of the memory corruption.
   </p>
   <p class="para">
    Such code can be made to work identically in both the pre-fix and the
    post-fix PHP versions. The signature of <em>func()</em> can
    be altered to return by reference, or the reference assignment can be
    removed from the result of <em>func()</em>.
   </p>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">function&nbsp;</span><span style="color: #0000BB">func</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #DD0000">'function&nbsp;return'</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">$x&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'original&nbsp;value'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$y&nbsp;</span><span style="color: #007700">=&amp;&nbsp;</span><span style="color: #0000BB">$x</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$y&nbsp;</span><span style="color: #007700">=&nbsp;&amp;</span><span style="color: #0000BB">func</span><span style="color: #007700">();<br />echo&nbsp;</span><span style="color: #0000BB">$x</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
   <p class="para">
    In PHP 4.3 <var class="varname"><var class="varname">$x</var></var> would be &#039;original value&#039;, whereas after
    the changes it would be &#039;function return&#039; - remember that where the
    function does not return by reference, the reference assignment is
    converted to a regular assignment. Again, this can be brought to a common
    base, either by forcing <em>func()</em> to return by reference
    or by eliminating the by-reference assignment.
   </p>
  </div>

  <div class="section" id="migration51.references-error">
   <h2 class="title">Code that worked under PHP 4.3.x, but now throws an error</h2>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">class&nbsp;</span><span style="color: #0000BB">Foo&nbsp;</span><span style="color: #007700">{<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;function&nbsp;</span><span style="color: #0000BB">getThis</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">$this</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;}<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;function&nbsp;</span><span style="color: #0000BB">destroyThis</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$baz&nbsp;</span><span style="color: #007700">=&amp;&nbsp;</span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">getThis</span><span style="color: #007700">();<br />&nbsp;&nbsp;&nbsp;&nbsp;}<br />}<br /><br /></span><span style="color: #0000BB">$bar&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">Foo</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$bar</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">destroyThis</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$bar</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
   <p class="para">
    In PHP 5.0.3, <var class="varname"><var class="varname">$bar</var></var> evaluated to <strong><code>NULL</code></strong>
    instead of returning an object. That happened because
    <em>getThis()</em> returns by value, but the value here is
    assigned by reference. Although it now works in the expected way, this is
    actually invalid code which will throw an <strong><code>E_NOTICE</code></strong>
    under PHP 4.4 or an <strong><code>E_STRICT</code></strong> under PHP 5.0.4 and up.
   </p>
  </div>

  <div class="section" id="migration51.references-works">
   <h2 class="title">Code that failed under PHP 4.3.x, but now works</h2>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">function&nbsp;&amp;</span><span style="color: #0000BB">f</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$x&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">"foo"</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$x</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;print&nbsp;</span><span style="color: #DD0000">"</span><span style="color: #0000BB">$x</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;return(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br />}<br /><br />for&nbsp;(</span><span style="color: #0000BB">$i&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">0</span><span style="color: #007700">;&nbsp;</span><span style="color: #0000BB">$i&nbsp;</span><span style="color: #007700">&lt;&nbsp;</span><span style="color: #0000BB">3</span><span style="color: #007700">;&nbsp;</span><span style="color: #0000BB">$i</span><span style="color: #007700">++)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$h&nbsp;</span><span style="color: #007700">=&nbsp;&amp;</span><span style="color: #0000BB">f</span><span style="color: #007700">();<br />}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <p class="para">
     In PHP 4.3 the third call to <span class="function"><a href="function.var-dump.html" class="function">var_dump()</a></span> produces
     <strong><code>NULL</code></strong>, due to the memory corruption caused by
     returning an uninitialized value by reference. This is valid code
     in PHP 5.0.4 and up, but threw errors in earlier releases of PHP.
    </p>
   </div>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$arr&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'a1'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;array(</span><span style="color: #DD0000">'alfa'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">'ok'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">$arr&nbsp;</span><span style="color: #007700">=&amp;&nbsp;</span><span style="color: #0000BB">$arr</span><span style="color: #007700">[</span><span style="color: #DD0000">'a1'</span><span style="color: #007700">];<br />echo&nbsp;</span><span style="color: #DD0000">'-'</span><span style="color: #007700">.</span><span style="color: #0000BB">$arr</span><span style="color: #007700">[</span><span style="color: #DD0000">'alfa'</span><span style="color: #007700">].</span><span style="color: #DD0000">"-\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <p class="para">
     Until PHP 5.0.5, it wasn&#039;t possible to assign an array element by
     reference in this way. It now is.
    </p>
   </div>
  </div>

  <div class="section" id="migration51.references-didnotwork">
   <h2 class="title">Code that <em>should have worked</em> under PHP 5.0.x</h2>
   <p class="para">
    There are a couple of instances of bugs reported under PHP 5.0 prior to
    the reference fixes which now &#039;work&#039;. However, in both cases errors are
    thrown by PHP 5.1.x, because the code was invalid in the first place.
    Returning values by reference using <em>self::</em> now works
    in the general case but throws an <strong><code>E_STRICT</code></strong> warning,
    and although your mileage may vary when assigning by reference to an
    overloaded object, you will still see an <strong><code>E_ERROR</code></strong>
    when you try it, even where the assignment itself appears to work.
   </p>
  </div>

  <div class="section" id="migration51.references-warnings">
   <h2 class="title">Warnings that came and went</h2>
   <p class="para">
    Nested calls to functions returning by reference are valid code under both
    PHP 4.3.x and PHP 5.1.x, but threw an unwarranted
    <strong><code>E_NOTICE</code></strong> or <strong><code>E_STRICT</code></strong> under the
    intervening PHP releases.
   </p>
   <div class="informalexample">
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">function&nbsp;&amp;&nbsp;</span><span style="color: #0000BB">foo</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$var&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'ok'</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">$var</span><span style="color: #007700">;<br />}<br /><br />function&nbsp;&amp;&nbsp;</span><span style="color: #0000BB">bar</span><span style="color: #007700">()&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">foo</span><span style="color: #007700">();<br />}<br /><br /></span><span style="color: #0000BB">$a&nbsp;</span><span style="color: #007700">=&amp;&nbsp;</span><span style="color: #0000BB">bar</span><span style="color: #007700">();<br />echo&nbsp;</span><span style="color: #DD0000">"</span><span style="color: #0000BB">$a</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </div>
 </div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="migration51.changes.html">Key PHP 5.1.x features</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="migration51.reading.html">Reading []</a></div>
 <div class="up"><a href="migration51.html">Migrating from PHP 5.0.x to PHP 5.1.x</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
